feat(webapp): dashboard agent — chat, reports, Investigate, Watch - #4418

apps/webapp/seed-agent-examples.mts-1598-1614 (1)

1598-1614: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

?.value ? … : undefined collapses a legitimate zero into the fallback.

pending, donePerMin, triggeredPerMin and drainMinutes all treat a reported 0 as "absent" and fall back to the STORY.* constants. On a recovered or quiet stand the card would read 0 pending while the prose quotes 4,812 — the exact disagreement this function exists to prevent. Use a nullish check instead.

🐛 Guard on presence, not truthiness

-    pending: metric("pending")?.value ? Math.round(metric("pending")!.value) : undefined,
+    pending: metric("pending")?.value != null ? Math.round(metric("pending")!.value) : undefined,
     worstQueueShare: flow?.attribution?.dim === "queue" ? flow.attribution.share : undefined,
-    donePerMin: vm.facts?.throughput?.donePerMin
+    donePerMin: vm.facts?.throughput?.donePerMin != null
       ? Math.round(vm.facts.throughput.donePerMin)
       : undefined,
-    triggeredPerMin: vm.facts?.throughput?.triggeredPerMin
+    triggeredPerMin: vm.facts?.throughput?.triggeredPerMin != null
       ? Math.round(vm.facts.throughput.triggeredPerMin)
       : undefined,
-    drainMinutes: drain?.value ? Math.round(drain.value) : undefined,
+    drainMinutes: drain?.value != null ? Math.round(drain.value) : undefined,

apps/webapp/seed-queue-metrics.mts-581-597 (1)

581-597: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

DELETE without mutations_sync races the seeding insert that follows.

--reset runs these deletes and then line 941 inserts immediately. The sibling seeder guards the identical sequence with SETTINGS mutations_sync = 2 and explains why: left asynchronous, the re-seed races its own predecessor and leaves a second copy of the data behind. Worth setting async_insert: 0 on line 572 too, so the rows are visible to the OPTIMIZE … FINAL calls on lines 949-952.

🐛 Make the reset finish before seeding

     await raw.command({
-      query: `DELETE FROM trigger_dev.${table} WHERE environment_id = '${environmentId}'`,
+      query: `DELETE FROM trigger_dev.${table} WHERE environment_id = '${environmentId}' SETTINGS mutations_sync = 2`,
     });

apps/webapp/seed-agent-examples-chats.mts-338-339 (1)

338-339: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use the COMPLETED_WITH_ERRORS status literal in the TRQL query.

Failed is not a standard run status in Trigger.dev TRQL; use status = 'COMPLETED_WITH_ERRORS' so the seeded failed runs are counted.

apps/webapp/seed-queue-metrics.mts-1-6 (1)

1-6: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Keep this seeder consistent with seed-agent-examples.mts's documented interop pattern.

seed-agent-examples.mts disables the sibling import-entry CommonJS boundary instead of running into the documented named-import loading failure, so this script should use the same default-binding import/interworking pattern.

internal-packages/dashboard-agent-contracts/src/blocks.ts-133-146 (1)

133-146: 🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win

Require http(s) on docs action targets.

target is documented as “an https URL” for docs actions, but the schema accepts any string. Since this field is LLM-authored UI input, prefer narrowing it to http:// or https:// URLs in the schema rather than leaving the contract to later validation.

apps/webapp/app/services/dashboardAgentWatchChecks.ts-146-175 (1)

146-175: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Make unreliable queued wait labels include the stale-first-enqueue caveat.

For WAITING_TO_RESUME / RETRYING_AFTER_FAILURE / PAUSED, run.queuedAt is not a current queue entry, but this path still emits waitBasis: "queued_at" and a confident queued for … label. Bake the caveat into the label or omit the label when queueWaitReliable is false so it can’t be surfaced as a current wait time downstream.

♻️ Make the label carry its own caveat

   if (run.queuedAt) {
     const waitMs = Math.max(0, end.getTime() - run.queuedAt.getTime());
     return {
       waitMs,
       waitBasis: "queued_at",
-      waitLabel: `queued for ${formatMs(waitMs)}`,
+      waitLabel: queueWaitReliable
+        ? `queued for ${formatMs(waitMs)}`
+        : `time since first enqueue: ${formatMs(waitMs)}`,
       queueWaitReliable,
     };
   }

apps/webapp/app/components/dashboard-agent/DashboardAgentMessages.tsx-163-180 (1)

163-180: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

CitationButton renders different elements on server vs client.

path is always null during SSR, so the server emits a LinkButton anchor while the first client render emits a Button — a hydration mismatch for every same-origin citation. Compute the path from sameOriginPath after mount (or keep one element type and branch inside onClick).

♻️ One option: single element, branch on click

 function CitationButton({ url, label }: { url: string; label: string }) {
   const navigate = useNavigate();
-  const path = typeof window === "undefined" ? null : sameOriginPath(url, window.location.origin);
-
-  if (path) {
-    return (
-      <Button variant="docs/small" LeadingIcon={BookOpenIcon} onClick={() => navigate(path)}>
-        {label}
-      </Button>
-    );
-  }
-
   return (
-    <LinkButton to={url} variant="docs/small" LeadingIcon={BookOpenIcon}>
+    <LinkButton
+      to={url}
+      variant="docs/small"
+      LeadingIcon={BookOpenIcon}
+      onClick={(event) => {
+        const path = sameOriginPath(url, window.location.origin);
+        if (!path) return;
+        event.preventDefault();
+        navigate(path);
+      }}
+    >
       {label}
     </LinkButton>
   );
 }

apps/webapp/app/components/dashboard-agent/DashboardAgentPanel.tsx-166-189 (1)

166-189: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Post-mutation reloads can coalesce onto a pre-mutation request.

loadHistory returns the in-flight promise, so the void loadHistory() calls in deleteChat (Line 422) and cancelWatch (Line 452) can piggyback on a GET that was issued before the POST landed and re-render the stale list — the deleted chat reappears, or the cancelled watch chip comes back, until something else triggers a reload. Chain a fresh request after the in-flight one instead of returning it.

🐛 Sketch: let callers ask for post-mutation freshness

-  const loadHistory = useCallback(async () => {
-    if (historyInFlight.current) return historyInFlight.current;
+  const loadHistory = useCallback(async (options?: { fresh?: boolean }) => {
+    if (historyInFlight.current) {
+      // A reload after a mutation must not adopt a request that was already
+      // in flight before it — that result predates the change.
+      if (!options?.fresh) return historyInFlight.current;
+      await historyInFlight.current;
+    }
     const request = (async () => {

Then call void loadHistory({ fresh: true }) from deleteChat and cancelWatch.

apps/webapp/app/components/dashboard-agent/RunDiagnosisCard.tsx-161-177 (1)

161-177: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

An enabled button that does nothing is a real click target outside the gallery.

useRunPath returns undefined whenever org/project/env context is missing — the storybook gallery is one such case, but any future host without that context is another. A user clicking gets silence with no feedback. Prefer disabled (or a tooltip explaining why) so the inert state is honest, and keep the gallery's visual review by passing an explicit prop rather than inferring it from missing context.

apps/webapp/test/dashboardAgentWatchChecks.test.ts-123-134 (1)

123-134: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Assert the label in the stale-queuedAt case — that's the invariant this file exists to pin.

The header calls out the wait label as the thing that must never call a time-from-creation a queue wait, but this test only checks queueWaitReliable and waitBasis. A regression that emitted "queued for 10m" for an untrustworthy queuedAt on a resumed run would still pass. Add the label (and the result) assertion.

💚 Proposed addition

     expect(outcome.facts.queueWaitReliable).toBe(false);
     expect(outcome.facts.waitBasis).toBe("queued_at");
+    expect(outcome.result).toBe("pending");
+    // Reliability is false, so the label must not claim a queue wait.
+    expect(outcome.facts.waitLabel).not.toMatch(/queued for/);

internal-packages/dashboard-agent/src/tools.ts-429-448 (1)

429-448: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Wrap the body read so an aborted/interrupted response doesn't escape as a throw.

The fetch call is guarded but await res.text() on Line 431 is not. If the 30s abort fires while the body is streaming (or the connection resets mid-body), this rejects and the throw escapes searchTriggerDocs, breaking the documented "returns { error }" contract that search_docs relies on.

🛡️ Proposed fix

   if (!res.ok) return { error: `The docs search failed (status ${res.status}).` };
 
-  const body = await res.text();
+  let body: string;
+  try {
+    body = await res.text();
+  } catch (error) {
+    return { error: `Couldn't read the docs response: ${(error as Error).message}` };
+  }
   let payload: any;

internal-packages/dashboard-agent/src/tools.ts-872-883 (1)

872-883: 🚀 Performance & Scalability | 🟡 Minor | ⚡ Quick win

list_errors doesn't clamp period, unlike list_runs and list_deploys.

Lines 845 and 1096 both run the model-supplied period through clampPeriod; Line 877 forwards it raw. Unless the errors route clamps server-side, the model can request an unbounded window here.

♻️ Proposed fix

       execute: async ({ status, taskIdentifier, search, period, limit }) => {
+        const effectivePeriod = period ? clampPeriod(period) : undefined;
         const sp = new URLSearchParams();
         if (status) sp.append("filter[status]", status);
         if (taskIdentifier) sp.append("filter[taskIdentifier]", taskIdentifier);
         if (search) sp.append("filter[search]", search);
-        if (period) sp.append("filter[period]", period);
+        if (effectivePeriod) sp.append("filter[period]", effectivePeriod);

apps/webapp/app/routes/api.v1.queues.$queueParam.metrics.ts-72-78 (1)

72-78: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Rounding endMs up with Math.ceil includes future time in the averaged window.

Because endMs is rounded up to the next bucket boundary, it can be ahead of Date.now() by up to bucketSeconds (as much as ~1/12 of the requested period). startedPerMin and other rate fields then divide the real (bounded) count by a window that partly hasn't happened yet, systematically under-reporting throughput/rate by the same proportion. Math.floor gives identical cache-alignment benefits without ever querying/averaging over future time.

🐛 Proposed fix

-    const endMs = Math.ceil(Date.now() / (bucketSeconds * 1000)) * bucketSeconds * 1000;
+    const endMs = Math.floor(Date.now() / (bucketSeconds * 1000)) * bucketSeconds * 1000;

Also applies to: 124-126

apps/webapp/app/components/dashboard-agent/demo/components/DemoChartCard.tsx (1)

12-30: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Duplicate chart-card frame markup — parameterize rows instead of reimplementing the frame for the empty state.
DemoChartCard hardcodes rows={demoChart.rows} with no way to override it, so the gallery's empty-chart state had to copy the entire border/title-strip/height JSX just to pass rows={[]}.

• apps/webapp/app/components/dashboard-agent/demo/components/DemoChartCard.tsx#L12-L30: accept an optional rows prop (defaulting to demoChart.rows) so callers can override the dataset.
• apps/webapp/app/routes/storybook.agent-ui/route.tsx#L300-L317: replace EmptyChartCard's duplicated JSX with <DemoChartCard rows={[]} /> (or equivalent) once the prop exists.

apps/webapp/app/routes/storybook.agent-ui/route.tsx (1)

397-436: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider deriving untrustworthyReport via the real stale-guard function rather than hand-rolling its output shape.

The comment above this block states it's "Derived exactly the way applyStaleGuard does it," but the code manually reconstructs the transformation instead of calling that function. If applyStaleGuard (or equivalent) is exported and importable here, calling it directly would guarantee this fixture never drifts from the real stale-telemetry behavior it's meant to demonstrate.

Please confirm whether the health report's stale-guard transformation (referenced as applyStaleGuard) is exported in a form importable from this route (e.g. from apps/webapp/app/presenters/v3/reports/health/health.ts), so this fixture could call it directly instead of duplicating its logic.

apps/webapp/app/components/dashboard-agent/demo/demo.test.ts (1)

34-39: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

The isolation guard misses side-effect and dynamic imports.

importSpecifiers only matches … from "x", so import "~/foo.server" and await import("~/db.server") slip through the very check on lines 369-378 that exists to catch them.

♻️ Broaden the specifier scan

-/** Every import specifier in a file, from both `import` and `export … from`. */
+/** Every module specifier in a file: `from "x"`, `import "x"` and `import("x")`. */
 function importSpecifiers(source: string): string[] {
-  return [...source.matchAll(/(?:import|export)[\s\S]*?from\s+["']([^"']+)["']/g)].map(
-    (match) => match[1]!
-  );
+  return [
+    ...source.matchAll(/from\s+["']([^"']+)["']/g),
+    ...source.matchAll(/\bimport\s*\(\s*["']([^"']+)["']/g),
+    ...source.matchAll(/\bimport\s+["']([^"']+)["']/g),
+  ].map((match) => match[1]!);
 }

apps/webapp/seed-agent-examples-chats.mts (1)

257-257: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Import VIEW_BLOCK_VERSION instead of hardcoding version: 1.

The demo fixtures stamp the envelope from the contracts constant; these seeded blocks hardcode 1. If the contract version is bumped, the strict envelope schema rejects these blocks and the cards silently degrade to plain tool rows — exactly the failure mode the transcripts exist to demonstrate. The package is already imported on line 29.

♻️ Use the contract constant

-import { formatTriggerUri } from "`@internal/dashboard-agent-contracts`";
+import { formatTriggerUri, VIEW_BLOCK_VERSION } from "`@internal/dashboard-agent-contracts`";

-  const diagnosisEnvelope = { id: `diag_${w.failedRunId}`, version: 1 };
+  const diagnosisEnvelope = { id: `diag_${w.failedRunId}`, version: VIEW_BLOCK_VERSION };

   const failuresChart = {
     id: "chart_failures_by_task",
     revision: 0,
-    version: 1,
+    version: VIEW_BLOCK_VERSION,

   const pendingChart = {
     id: "chart_pending_runs",
     revision: 0,
-    version: 1,
+    version: VIEW_BLOCK_VERSION,

Also applies to: 332-362

apps/webapp/test/seedAgentExamplesChats.test.ts (1)

176-178: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Read the kind with the contracts parser rather than split("/")[4].

Positional indexing silently mis-classifies if the URI layout changes — a run URI read as report would skip the resolution assertion entirely, and the test would still pass. demo.test.ts uses safeParseTriggerUri for exactly this.

♻️ Parse instead of index

     for (const uri of uris) {
-      const kind = uri.split("/")[4];
-      if (UNRESOLVABLE_KINDS.includes(kind)) continue;
+      const parsed = safeParseTriggerUri(uri);
+      expect(parsed.success, uri).toBe(true);
+      if (!parsed.success || UNRESOLVABLE_KINDS.includes(parsed.data.kind)) continue;
       const resolved = resolveTriggerUri(SCOPE, uri);

Add the import:

import { safeParseTriggerUri } from "`@internal/dashboard-agent-contracts`";

internal-packages/dashboard-agent-contracts/src/trigger-uri.ts (1)

320-341: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value

Duplicate line params are silently accepted, last one wins.

trigger://…/source/abc/a.ts?line=1&line=2 parses as line: 2. Everything else in the grammar rejects non-canonical input (fragments, unknown params, empty segments), so accepting a duplicate here is inconsistent and lets two different URIs mean the same resource.

♻️ Reject duplicates

   for (const [key, value] of params) {
     if (key !== "line") {
       return { success: false, error: `unknown query param "${key}"` };
     }
 
+    if (line !== undefined) {
+      return { success: false, error: "duplicate query param \"line\"" };
+    }
+
     if (!/^\d+$/.test(value) || Number(value) < 1) {

internal-packages/dashboard-agent/src/watch-tick.ts (1)

212-224: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

wakeAction infers the action type from "not fired".

If isTerminalWatchStatus ever admits a third terminal status (e.g. cancelled, which the contract's watchStatusSchema includes), the delivery-only path produces type: "watch.expired" with id: watch:<id>:cancelled — a type/id pair that doesn't describe what happened. Switching on the status explicitly keeps that from slipping through silently.

♻️ Switch on the status

 function wakeAction(watch: Watch, facts: Record<string, unknown>): WatchWakeAction {
   const spec = watch.spec as PersistedWatchSpec;
+  if (watch.status !== "fired" && watch.status !== "expired") {
+    throw new Error(`cannot build a wake for a ${watch.status} watch`);
+  }
   return {
-    type: watch.status === "fired" ? "watch.fired" : "watch.expired",
+    type: watch.status === "fired" ? "watch.fired" : "watch.expired",

internal-packages/dashboard-agent/src/dashboard-agent.eval.ts (1)

582-585: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use APICallError.isInstance(error) for provider error detection.

error.name.includes("APICallError") depends on the error name surviving any wrapping or renaming; the SDK’s provided type guard is more reliable.

♻️ Use the SDK's type guard

-      const infra = error instanceof Error && error.name.includes("APICallError");
+      const infra = APICallError.isInstance(error);

plus import { APICallError } from "ai";

internal-packages/dashboard-agent/src/dashboard-agent.test.ts (1)

429-432: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Poll the eval-enqueue side effect instead of relying on a fixed sleep.

turnAtRate waits only 30 ms before returning calls, which can still fail when the runner is loaded. Move the assertion out of the helper and make it wait for the expected call count, e.g. vi.waitFor(() => expect(calls).toHaveLength(1), { timeout: 2000 }); for the rate-0 path keep a bounded wait on “still empty” if needed.

internal-packages/dashboard-agent-contracts/src/watch.ts (1)

38-61: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider z.discriminatedUnion("kind", [...]) instead of z.union.

All five branches share a literal kind discriminator, so this is a textbook case for z.discriminatedUnion. With plain z.union, an invalid payload (e.g., wrong kind or a bad runId) produces a combined invalid_union error listing every failed branch, which is noisier to surface back to the agent/tool-caller than the targeted error discriminatedUnion gives.

♻️ Proposed refactor

-export const watchSpecSchema = z.union([
+export const watchSpecSchema = z.discriminatedUnion("kind", [
   watchCommonSchema
     .extend({ kind: z.literal("run_start"), runId: z.string() })
     .merge(runStateCadenceSchema),

internal-packages/dashboard-agent-db/src/queries.ts (1)

684-698: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract the shared unread-wake predicate.

The same (last_read_at is null or coalesce(fired_at, last_checked_at) > last_read_at) clause plus the status in ('fired','expired') + tenancy join is repeated verbatim in countUnreadWatchWakes, listUnreadWatchWakes (Line 744), and listChatIdsWithUnreadWakes (Line 783). One helper returning the and(...) condition keeps the wake definition single-sourced — the doc comments already assert all three share it.

♻️ Sketch

+function unreadWakeCondition(params: { organizationId: string; userId: string }) {
+  return and(
+    inArray(watches.status, ["fired", "expired"]),
+    eq(chats.organizationId, params.organizationId),
+    eq(chats.userId, params.userId),
+    isNull(chats.deletedAt),
+    sql`(${chats.lastReadAt} is null or coalesce(${watches.firedAt}, ${watches.lastCheckedAt}) > ${chats.lastReadAt})`
+  );
+}

internal-packages/dashboard-agent/VERDICTS.md (1)

104-108: 📐 Maintainability & Code Quality | 🔵 Trivial

Track the documented queuedDuration bug.

RunPresenter.server.ts computing queuedDuration as startedAt − createdAt is recorded here as knowingly unfixed, which over-reports for delayed/scheduled runs in the dashboard. Want me to open an issue so it doesn't only live in this markdown file?

internal-packages/dashboard-agent/src/dashboard-agent.ts (1)

622-626: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use the same non-null assertion as withCacheBreakpointOnLast.

sanitized[sanitized.length - 1] is typed ModelMessage | undefined under noUncheckedIndexedAccess, and it's then spread at Line 628. The helper at Line 378 already handles this with !; mirror it here so the two paths type-check identically.

♻️ Proposed tweak

-    const last = sanitized[sanitized.length - 1];
+    const last = sanitized[sanitized.length - 1]!;

internal-packages/dashboard-agent/src/tool-schemas.ts (1)

398-403: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Validate the alert email shape in the schema.

email accepts any string, so a malformed value only fails downstream (or worse, gets persisted as a subscription address). z.string().email() makes the model's mistake a tool-validation error it can correct in-turn.

♻️ Proposed change

     email: z
-      .string()
+      .string()
+      .email()
       .optional()
       .describe("Email to alert. Omit to use the user's own account email."),

apps/webapp/app/components/dashboard-agent/DashboardAgentMessages.tsx (1)

92-97: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

unknown[] + as never throws away the block contract.

blocksFor returns unknown[], forcing blocks as never at the ViewBlocks call site, so a block-shape change in @internal/dashboard-agent-contracts won't surface at compile time here. Typing the return as the catalog's block union would keep the boundary checked.

Also applies to: 222-228

apps/webapp/app/components/dashboard-agent/DashboardAgentPanel.tsx (1)

471-476: 🚀 Performance & Scalability | 🔵 Trivial | 💤 Low value

?? [] hands a new array down on every render.

chatWatches gets a fresh identity each render, which flows into DashboardAgentChat → DashboardAgentMessages and defeats the memo on DashboardAgentTurn (its watches prop always compares unequal). A module-level const NO_WATCHES: WatchChip[] = [] fallback keeps the reference stable.

apps/webapp/app/components/dashboard-agent/DashboardAgentSuggestedPrompts.tsx (1)

58-65: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Name the "no page context" fallback.

The inline { page: { kind: "other", path: "" }, signals: [] } is a placeholder context built at the call site; a shared named constant (e.g. UNKNOWN_PAGE_CONTEXT in suggested-prompts/registry.ts) keeps the meaning of the empty path explicit and reusable.

As per coding guidelines: "Use named constants for sentinel or placeholder values instead of scattering raw string literals across comparisons."

Source: Coding guidelines

apps/webapp/app/components/dashboard-agent/suggested-prompts/registry.ts (1)

217-222: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

SIGNAL_PRIORITY isn't exhaustiveness-checked, and the two iterators duplicate one loop.

SIGNAL_SLOT is a Record<AgentPageSignalKind, …>, so a new signal kind fails to compile there — but SIGNAL_PRIORITY is a bare array, and since both iterators drive off it, a kind missing from the array silently never produces a chip. contextualPrompts is also contextualPromptsBySlot flattened in slot order.

♻️ Make the priority list exhaustive and derive the flat list

-export const SIGNAL_PRIORITY: AgentPageSignalKind[] = [
+// A tuple typed against the kind union: omitting a new kind is a compile error.
+export const SIGNAL_PRIORITY = [
   "fresh_failure",
   "waiting_run",
   "slow_run",
   "concurrency_saturation",
-];
+] as const satisfies readonly AgentPageSignalKind[];

 export function contextualPrompts(context: AgentPageContext, now: number): SuggestedPrompt[] {
-  const prompts: SuggestedPrompt[] = [];
-  for (const kind of SIGNAL_PRIORITY) {
-    for (const signal of context.signals) {
-      if (signal.kind !== kind) continue;
-      const prompt = promptForSignal(signal, now);
-      if (prompt) prompts.push(prompt);
-    }
-  }
-  return prompts;
+  const bySlot = contextualPromptsBySlot(context, now);
+  return PROMPT_SLOTS.flatMap((slot) => bySlot[slot]);
 }

Note: this changes contextualPrompts ordering from signal-priority to slot order — keep the current loop if callers depend on the former.

Also applies to: 284-320

apps/webapp/app/components/dashboard-agent/ReportView.tsx (1)

37-39: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Comment describes a registration side effect that doesn't exist.

healthMessages is used purely as a value in the static CATALOGS map on Line 89 — nothing self-registers on import. Worth correcting so a future reader doesn't assume adding an import is enough to register a new report's catalog.

apps/webapp/app/components/dashboard-agent/agent-badges.tsx (1)

46-46: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Hand-rolled icon component signature duplicated across two files. Both files type heroicons components as a bare call signature returning JSX.Element, which is version-sensitive (ForwardRefExoticComponent's call signature returns ReactNode) and duplicated rather than shared.

• apps/webapp/app/components/dashboard-agent/agent-badges.tsx#L46-L46: change the exported IconComponent alias to React.ComponentType<{ className?: string }>.
• apps/webapp/app/components/dashboard-agent/WakeBanner.tsx#L77-L82: import IconComponent from ./agent-badges and type TONE_ICON as Record<AgentTone, IconComponent> instead of restating the signature inline.

apps/webapp/app/components/dashboard-agent/suggested-prompts/dismissal.ts (1)

28-35: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Dismissals are permanent and the key set is never pruned.

Every dismissed id leaves a key behind forever, including operator-controlled promoted-prompt ids that rotate. Consider storing a timestamp instead of "1" so stale entries can expire (and a chip can come back after a while), or prune on read.

apps/webapp/app/components/dashboard-agent/suggested-prompts/page-mappers.test.ts (1)

192-195: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Test name contradicts its fixture.

running: 10 against a concurrencyLimit of 10 is at the limit, not "idle under its limit" — the case being covered is "at capacity with an empty queue". Renaming keeps the boundary this test pins obvious.

apps/webapp/app/components/dashboard-agent/suggested-prompts/resolver.test.ts (1)

164-172: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

toContain("") passes vacuously if the fixture changes kind.

Line 223 in this same file already uses the stronger pattern (throw new Error("fixture changed")); the ternary here silently degrades to an assertion that can never fail. Prefer the narrowing guard for consistency.

♻️ Proposed change

   it("sends the full prompt text, not the short label", () => {
     const [failure] = resolveSuggestedPrompts(demoPageContexts.failedRun, { now: NOW });
+    const page = demoPageContexts.failedRun.page;
+    if (page.kind !== "run") throw new Error("fixture changed");
 
     expect(failure?.label).toBe("Why did this run fail?");
-    expect(failure?.prompt).toContain(
-      demoPageContexts.failedRun.page.kind === "run" ? demoPageContexts.failedRun.page.runId : ""
-    );
+    expect(failure?.prompt).toContain(page.runId);
     expect(failure?.prompt).toContain("12m ago");
   });

internal-packages/dashboard-agent/src/tools.ts (3)

596-624: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Misplaced doc block: the renderInvestigations docs sit on canonicalizeEvidence.

Two doc comments are stacked here; the first (Lines 596-613, describing block stamping and continueId) documents renderInvestigations, which is declared at Line 706. Move it there so tooling and readers attach it correctly.

---

722-779: 🗄️ Data Integrity & Integration | 🔵 Trivial | 💤 Low value

Two investigation blocks in one view collapse into one row.

currentInvestigationId is assigned from the first block's upsert, so a second investigation block in the same render_view call revises the first rather than creating a second investigation — both blocks then carry the same id with different revisions. If the schema permits multiple investigation blocks per view, consider rejecting that up front (or scoping the id per block) rather than silently merging.

---

1078-1089: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Comment says "double-encode" but the code encodes once.

Line 1081 applies encodeURIComponent a single time (task/my-task → task%2Fmy-task), which is what the route's un-escaping expects. Reword the comment. Also worth noting: unlike the neighbouring tools, this returns result.data verbatim, so any series/histogram fields in the metrics payload land straight in the model's context — consider a curateQueue in line with curateReport.

apps/webapp/app/routes/api.v1.projects.$projectRef.$env.runs.$runId.commit.ts (1)

27-37: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Parse the git JSON blob with zod instead of a bare cast.

deployment.git is untyped Prisma JSON; the cast asserts a shape that is never checked, so a legacy/oddly-shaped blob would flow straight into the API response (e.g. pullRequestNumber as a string). A small z.object({...}).partial().safeParse() keeps the response contract honest.

As per coding guidelines: "Use zod for validation in packages/core and apps/webapp".

♻️ Proposed refactor

-type GitMetaBlob = {
-  source?: string;
-  commitAuthorName?: string;
-  commitMessage?: string;
-  commitRef?: string;
-  remoteUrl?: string;
-  ghUsername?: string;
-  pullRequestNumber?: number;
-  pullRequestTitle?: string;
-  pullRequestState?: string;
-};
+const GitMetaBlob = z
+  .object({
+    source: z.string(),
+    commitAuthorName: z.string(),
+    commitMessage: z.string(),
+    commitRef: z.string(),
+    remoteUrl: z.string(),
+    ghUsername: z.string(),
+    pullRequestNumber: z.number(),
+    pullRequestTitle: z.string(),
+    pullRequestState: z.string(),
+  })
+  .partial();

-    const git = (deployment?.git ?? undefined) as GitMetaBlob | undefined;
+    const parsedGit = deployment?.git ? GitMetaBlob.safeParse(deployment.git) : undefined;
+    const git = parsedGit?.success ? parsedGit.data : undefined;

Also applies to: 73-73

Source: Coding guidelines

apps/webapp/app/routes/api.v1.dashboard-agent.alerts.ts (1)

156-159: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Map ServiceValidationError from CreateAlertChannelService.call to a 4xx response.

The catch block currently treats all CreateAlertChannelService.call failures as 500, including user-input validation failures such as alert-channel limits. Distinguish ServiceValidationError here and return a 4xx, so the agent can explain the fixable failure instead of seeing an internal error.

apps/webapp/test/dashboardAgentRoutes.test.ts (1)

26-29: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Dead mock. vi.mock("~/env.server") just re-exports the original module, so it has no effect — either drop it or note why the module factory is needed (e.g. to force ESM interop ordering).

apps/webapp/test/dashboardAgentWatchToken.test.ts (1)

15-15: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Hardcoded UAT prefix can drift. WATCH_TOKEN_PREFIX is imported but tr_uat_ is literal; if the rbac package ever changes its prefix, the "disguised" tokens in the cross-rejection tests stop testing what they claim while still passing. Export/import the constant from @trigger.dev/rbac if available.

apps/webapp/test/dashboardAgentWatches.test.ts (1)

371-375: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Conditional assertion can pass vacuously. If second.ok were unexpectedly true the existingId check is skipped silently. Narrow with an early if (second.ok || !first.ok) throw new Error(...) (or expect.fail) before asserting.

apps/webapp/app/v3/services/alerts/deliverDashboardAgentWatchAlert.server.ts (1)

411-417: 🩺 Stability & Availability | 🔵 Trivial | 💤 Low value

Guard the cast before reading .code. Both predicates dereference an unknown value; a thrown null/undefined (or a primitive) turns the catch block itself into a TypeError, losing the original failure. A typeof error === "object" && error !== null prefix makes them safe.

🛡️ Proposed guard

 function isWebAPIPlatformError(error: unknown): error is WebAPIPlatformError {
-  return (error as WebAPIPlatformError).code === ErrorCode.PlatformError;
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as WebAPIPlatformError).code === ErrorCode.PlatformError
+  );
 }
 
 function isWebAPIRateLimitedError(error: unknown): error is WebAPIRateLimitedError {
-  return (error as WebAPIRateLimitedError).code === ErrorCode.RateLimitedError;
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as WebAPIRateLimitedError).code === ErrorCode.RateLimitedError
+  );
 }

apps/webapp/app/services/uatRoutePreamble.server.ts-31-34 (1)

31-34: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Accept case-insensitive Bearer schemes.

/^Bearer / rejects valid lowercase bearer authorization schemes, causing UAT requests to fall through and be rejected. Match the scheme case-insensitively.

Proposed fix

-    ?.replace(/^Bearer /, "")
+    ?.replace(/^Bearer\s+/i, "")

internal-packages/dashboard-agent-contracts/src/blocks.ts-470-525 (1)

470-525: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Two prose invariants aren't enforced alongside the two that are.

The superRefine enforces "remediation ⇒ concluded" and "checkNext ⇒ inconclusive", but:

• checkNext is guarded by length > 0 while remediation is guarded only by !== undefined, so checkNext: [] passes on a concluded investigation whereas remediation: "" is rejected on an inconclusive one. The asymmetry lets a model send an empty checkNext on any outcome.
• progress's description says "Only while in_progress" (Line 486) but nothing rejects it on a terminal outcome, so a concluded card can still carry a live-progress string that the renderer may show.

Both are model-supplied fields, so the schema is the only gate.

🛠️ Proposed tightening

-      if (investigation.remediation !== undefined && investigation.outcome !== "concluded") {
+      if (investigation.remediation?.trim() && investigation.outcome !== "concluded") {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           path: ["remediation"],
           message: "Only a concluded investigation can offer a fix.",
         });
       }
-      if (
-        investigation.checkNext !== undefined &&
-        investigation.checkNext.length > 0 &&
-        investigation.outcome !== "inconclusive"
-      ) {
+      if (investigation.checkNext?.length && investigation.outcome !== "inconclusive") {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           path: ["checkNext"],
           message: "`checkNext` belongs to an inconclusive investigation.",
         });
       }
+      if (investigation.progress?.trim() && investigation.outcome !== "in_progress") {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["progress"],
+          message: "`progress` only belongs to an in_progress investigation.",
+        });
+      }

internal-packages/dashboard-agent-contracts/src/watch.ts-29-34 (1)

29-34: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

maxHours accepts fractional values below one cadence interval.

z.number().positive().max(24) admits e.g. 0.01, which yields an expiresAt earlier than the minimum 1-minute cadence — the first tick is then already final and the watch immediately expires as "not met by expiry". Since this value comes from the model, an integer floor of 1 keeps the lifecycle sane.

🛡️ Proposed fix

-  maxHours: z.number().positive().max(WATCH_MAX_HOURS),
+  maxHours: z.number().int().min(1).max(WATCH_MAX_HOURS),

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.alerts.new/route.tsx-460-471 (1)

460-471: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

The "Dashboard agent watches" checkbox isn't feature-gated. Every project sees this option, including orgs without dashboard-agent access, where the alert type can never fire. Consider gating it on the same access check the rest of the feature uses (surface a flag from the loader).

apps/webapp/app/v3/services/alerts/deliverDashboardAgentWatchAlert.server.ts-396-404 (1)

396-404: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Scalar fact values are never length-capped.

The doc comment promises "a cap so a big bag can't blow up an email or a Slack block", but only object values are truncated — String(value) for a long string passes through unbounded. An oversized fact produces an invalid Slack block, which #postSlackMessage maps to invalid_blocks → SkipRetryError, silently dropping the notification.

🐛 Proposed fix

     .map(([key, value]) => ({
       label: humanizeFactKey(key),
-      value: typeof value === "object" ? JSON.stringify(value).slice(0, 200) : String(value),
+      value: (typeof value === "object" ? JSON.stringify(value) : String(value)).slice(0, 200),
     }));

apps/webapp/app/components/dashboard-agent/demo/demo-chats.ts-527-573 (1)

527-573: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

watchCreatedAndWake mixes two unrelated watch scenarios.

The title ("Tell me when the backlog drains"), the intent object (demoIntents.watch, which wraps demoBacklogDrainWatch.spec — 5 min checks for up to 6h, queue demo-backlog-drain), and the headerWatches/{kind:"watches"} items (demoWatches.activeRow, which includes demoBacklogDrainWatch) all describe the backlog-drain watch. But the actual user message ("Tell me when the retry finishes"), assistant confirmation ("I'll check every minute for up to 2 hours"), and wake narration are all about demoRunFinishedWatch (the run-retry watch) instead. The cadence numbers in the intent's outcome text (5 min/6h) directly contradict the assistant's own text (1 min/2h) a few lines later.

This reads as if the chat was repurposed from a backlog-drain story to a run-retry story without updating the title/intent/watches references.

apps/webapp/app/components/dashboard-agent/demo/demo-chats.ts-726-762 (1)

726-762: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

docsAnswer title doesn't match its content.

Title is "How do I use batchTrigger?" but the user question, the search_docs tool call, and the entire answer are about retry/exponential-backoff behavior — batchTrigger is never mentioned.

🐛 Suggested fix

-  title: "How do I use batchTrigger?",
+  title: "How do retries actually work?",

apps/webapp/app/components/dashboard-agent/demo/demo-chats.ts-478-500 (1)

478-500: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

navigateRejectedIntent title doesn't match its content.

Title is "Take me to my deployments" (a navigation request), but the actual turn is "Just fix it for me" being rejected via demoIntents.proposeFix — unrelated to deployments or navigation. This is the history-list title, so it will mislead anyone browsing the demo chat registry in Storybook.

🐛 Suggested fix

-  title: "Take me to my deployments",
+  title: "Just fix it for me",

apps/webapp/app/components/dashboard-agent/demo/demo-chats.ts-180-230 (1)

180-230: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

investigateConcluded narration undercounts the hypotheses it actually tested.

The summary ("four tested hypotheses," line 185), the reasoning part ("Four candidates... run all four," lines 197-199), and the closing text ("Two of the four hold up," line 224) all describe a 4-hypothesis investigation. But demoInvestigationConcluded in fixtures/investigation.ts (lines 245-286) actually has 5 hypotheses — it also includes hyp-queue-burst (validated), so 3 of 5 hold up, not 2 of 4. The remediation text (line 244, "cap the queue's concurrency...") relies on that 5th hypothesis, so the data looks like the intended/complete version and the narration is stale.

For contrast, the sibling investigateInconclusive chat correctly matches its narration to its 3-hypothesis fixture, so this looks like an oversight specific to this chat rather than an intentional simplification.

🐛 Suggested fix

-          reasoningPart(
-            "Four candidates: the provider's rate limit, a bad payload, the retry schedule, and yesterday's deploy. Each one has a check that can rule it out, so run all four before writing a conclusion."
-          ),
+          reasoningPart(
+            "Five candidates: the provider's rate limit, a bad payload, the retry schedule, yesterday's deploy, and the queue bursting into the provider. Each one has a check that can rule it out, so run all five before writing a conclusion."
+          ),

and update the closing text/summary counts ("three of the five hold up") to match.

apps/webapp/app/components/dashboard-agent/demo/demo-chats.ts-575-617 (1)

575-617: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

watchExpiryAndCancel narration miscounts the watches shown.

The opening narration says: "Four watches from this conversation... One is still live... the rest have finished." But demoWatches.row (used for both headerWatches and the {kind:"watches"} item) has 5 entries, and 2 of them (demoRunFinishedWatch and demoBacklogDrainWatch) are active, not 1. So the actual chip row a reviewer sees will show 5 chips with 2 active ones, contradicting the "four... one still live" framing.

🐛 Suggested fix

Either narrate 5 watches with 2 still live, or scope the displayed row to the 4 the story actually describes (excluding `demoBacklogDrainWatch`, which belongs to a different scenario):

-{ kind: "watches", watches: demoWatches.row },
+{ kind: "watches", watches: [demoRunFinishedWatch, demoErrorRecurrenceWatch, demoHealthRecoveryWatch, demoCancelledWatch] },

internal-packages/dashboard-agent/src/tools.ts-429-448 (1)

429-448: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

await res.text() can throw past the { error } contract.

The fetch is guarded, but body reading isn't. On an abort (the 30s timeout at Line 1177) or a mid-stream socket reset, res.text() rejects and the exception escapes searchTriggerDocs, so search_docs throws instead of returning { error } — the convention this file states explicitly elsewhere ("Tools return {error}, never throw").

🛡️ Proposed fix

   if (!res.ok) return { error: `The docs search failed (status ${res.status}).` };
 
-  const body = await res.text();
+  let body: string;
+  try {
+    body = await res.text();
+  } catch (error) {
+    return { error: `Couldn't read the docs response: ${(error as Error).message}` };
+  }
   let payload: any;

apps/webapp/app/components/dashboard-agent/agent-badges.tsx-46-46 (1)

46-46: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use React’s component prop typing for the badge icon map.

@heroicons/react exports ForwardRefExoticComponent, not a function returning JSX.Element, so the direct assignments at lines 99, 127, and 155 may fail typecheck. Type this as React.ComponentType<{ className?: string }> instead.

apps/webapp/app/components/dashboard-agent/DashboardAgentMessages.tsx-163-180 (1)

163-180: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Render citation same-origin paths in a client-only SSR-safe way.

sameOriginPath(...) cannot work during SSR because location is browser-only, while window is falsy in the server pass. For same-origin citations, wrap this in ClientOnly/SSR-safe rendering so SSR passes the browser-ready Button branch and avoids a new-tab LinkButton vs client Button mismatch.

apps/webapp/app/components/dashboard-agent/suggested-prompts/promotedPrompt.server.ts-26-36 (1)

26-36: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Isolate the decorated flag read so the promoted chip can’t fail the environment layout.

makeFlag() reads prisma.featureFlag.findFirst() without catching Prisma failures, and this helper is awaited directly from the environment page loader. A flag-store hiccup on this optional, unsupported chip can turn the whole page into a 500, so catch and return undefined instead.

🛡️ Proposed fix

-  const flag = makeFlag();
-  const value = await flag({
-    key: FEATURE_FLAG.promotedDashboardAgentPrompt,
-    overrides: options?.orgFeatureFlags ?? {},
-  });
-
-  return parsePromotedPrompt(value);
+  try {
+    const flag = makeFlag();
+    const value = await flag({
+      key: FEATURE_FLAG.promotedDashboardAgentPrompt,
+      overrides: options?.orgFeatureFlags ?? {},
+    });
+
+    return parsePromotedPrompt(value);
+  } catch {
+    // A missing promoted chip is a supported state; a flag-store hiccup must not
+    // fail the layout loader.
+    return undefined;
+  }

apps/webapp/seed-agent-examples.mts (1)

2267-2296: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Wrap the tick in a try/catch so one transient failure doesn't end the heartbeat.

The loop awaits heartbeatTick with no error handling, and heartbeatTick itself has failure modes that are likely over a multi-hour run: prisma.taskRun.update on executingRunId (Lines 2145-2150) throws P2025 once that row is gone (e.g. a re-seed or manual delete), and the ClickHouse insert helpers call process.exit(1). Net effect: the stand silently stops being refreshed and the report ages into "stale telemetry" — exactly what heartbeat mode exists to prevent.

♻️ Suggested resilience for the tick loop

     const counts: string[] = [];
     for (const env of envs) {
-      const result = await heartbeatTick(ch, env, started, rng, nonce, tick, mode);
-      counts.push(
-        `${env.environment.slug} +${result.runs} runs +${result.metricRows} metric rows` +
-          (result.pruned > 0 ? ` -${result.pruned} pruned` : "")
-      );
+      try {
+        const result = await heartbeatTick(ch, env, started, rng, nonce, tick, mode);
+        counts.push(
+          `${env.environment.slug} +${result.runs} runs +${result.metricRows} metric rows` +
+            (result.pruned > 0 ? ` -${result.pruned} pruned` : "")
+        );
+      } catch (error) {
+        counts.push(
+          `${env.environment.slug} tick failed: ${error instanceof Error ? error.message : error}`
+        );
+      }
     }

And make the executing-run touch tolerant of a missing row:

   if (env.executingRunId) {
-    await prisma.taskRun.update({
-      where: { id: env.executingRunId },
-      data: { updatedAt: new Date(now) },
-    });
+    const { count } = await prisma.taskRun.updateMany({
+      where: { id: env.executingRunId },
+      data: { updatedAt: new Date(now) },
+    });
+    if (count === 0) env.executingRunId = null;
   }

internal-packages/dashboard-agent/src/watch-tick.ts (1)

139-155: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Validate body.result against watchCheckResultSchema instead of casting.

body.result is cast to WatchCheckResult with no runtime check, and only three of the four values are matched explicitly in runWatchTick. Any unexpected string falls into the pending branch and the watch keeps ticking until expiry. The contracts package already exports the enum schema.

♻️ Proposed change

-import type { WatchCheckResult } from "`@internal/dashboard-agent-contracts`";
+import { watchCheckResultSchema } from "`@internal/dashboard-agent-contracts`";
+import type { WatchCheckResult } from "`@internal/dashboard-agent-contracts`";

-  if (!body?.result) return { kind: "unavailable", detail: "the check returned no result" };
-  if (body.result === "unavailable") return { kind: "unavailable", detail: body.error };
-  return { kind: "result", result: body.result, facts: body.facts };
+  const result = watchCheckResultSchema.safeParse(body?.result);
+  if (!result.success) {
+    return { kind: "unavailable", detail: "the check returned no usable result" };
+  }
+  if (result.data === "unavailable") return { kind: "unavailable", detail: body?.error };
+  return { kind: "result", result: result.data, facts: body?.facts };

internal-packages/dashboard-agent-contracts/src/watch.ts (1)

38-61: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use z.discriminatedUnion("kind", …) for watchSpecSchema.

Each variant already has a kind discriminator, and this is the validated model input, so the targeted faster parsing and branch-specific validation error are worthwhile.

♻️ Proposed change

-export const watchSpecSchema = z.union([
+export const watchSpecSchema = z.discriminatedUnion("kind", [

internal-packages/dashboard-agent-db/src/queries.ts (1)

600-609: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use type aliases for these data shapes.

ActiveWatchSummary, UnreadWatchWake, and ChatWatchContext are plain data shapes, not behavioral contracts.

As per coding guidelines: "Use types over interfaces for TypeScript".

♻️ Proposed change

-export interface ActiveWatchSummary {
+export type ActiveWatchSummary = {

(and likewise for UnreadWatchWake / ChatWatchContext)

Also applies to: 701-709, 790-794

Source: Coding guidelines

internal-packages/dashboard-agent/VERDICTS.md (1)

70-71: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Point the {env} citation at trigger-uri.ts.

trigger-uri.ts is where the trigger:// URI grammar is defined and documents {env} as the RuntimeEnvironment id; page-context.ts only defines the page-context schema.

internal-packages/dashboard-agent/src/dashboard-agent.test.ts (1)

414-433: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Fixed 30 ms sleep can flake on loaded CI. onTurnComplete enqueues asynchronously; a hard-coded delay is the only thing keeping these three assertions honest. Consider polling with a short deadline instead.

♻️ Poll instead of sleeping

-    await harness.sendMessage(userMessage("hi"));
-    // onTurnComplete enqueues after the turn-complete chunk; give it a tick.
-    await new Promise((r) => setTimeout(r, 30));
-    return calls;
+    await harness.sendMessage(userMessage("hi"));
+    // onTurnComplete enqueues after the turn-complete chunk; wait for it (or
+    // settle) rather than betting on a fixed delay.
+    const deadline = Date.now() + 2000;
+    while (calls.length === 0 && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 10));
+    }
+    return calls;

Note the rate-0 case still needs a short settle window, so keep a small final tick for it.

apps/webapp/app/routes/api.v1.projects.$projectRef.$env.runs.$runId.commit.ts (1)

66-73: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Second deployment lookup is redundant and replica-lag prone.

resolveRunCommit already reads the deployment row with git selected on the primary (apps/webapp/app/services/dashboardAgent.server.ts Lines 224–229), then this route re-reads the same row from $replica keyed by version. Besides the extra query, a freshly created deployment that resolved on the primary may not be visible on the replica yet, silently dropping shortCode/deployedAt/git from the response. Consider having resolveRunCommit return the git metadata (and shortCode/deployedAt) it already has.

apps/webapp/test/dashboardAgentRoutes.test.ts (1)

26-29: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

This env.server mock is a no-op that still loads the real module.

importOriginal() evaluates ~/env.server, so its env-var validation runs and the suite depends on the ambient environment — while the mock itself changes nothing. Either drop the vi.mock entirely or return explicit stub values for the keys the routes read.

As per path instructions: "Do not import env.server.ts directly or indirectly into test files; instead pass environment-dependent values through options/parameters to make code testable".

Source: Path instructions

apps/webapp/test/dashboardAgentWatches.test.ts (2)

83-83: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Don't import env.server in the test; pass the signing secret in.

env is only used at Line 676 to read SESSION_SECRET for signDashboardAgentWatchToken. Use a literal test secret so the suite doesn't depend on the real env module loading and validating.

As per coding guidelines: "Test files must not import app/env.server.ts; pass configuration as options instead."

♻️ Proposed change

-const { env } = await import("~/env.server");
+const TEST_SESSION_SECRET = "test-session-secret";

   function tokenFor(watchId: string, expiresAt: Date) {
-    return signDashboardAgentWatchToken(env.SESSION_SECRET, { watchId, expiresAt });
+    return signDashboardAgentWatchToken(TEST_SESSION_SECRET, { watchId, expiresAt });
   }

Note: the route verifies with the real env.SESSION_SECRET, so this only works if the route's secret is also injected or the test sets process.env.SESSION_SECRET before import — worth confirming which seam you prefer.

Source: Coding guidelines

---

92-104: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Lexicographic migration ordering is fragile.

readdirSync().sort() matches the journal order only while every filename keeps a zero-padded numeric prefix. drizzle/meta/_journal.json is the authoritative order — reading idx/tag from it would make this replay correct by construction rather than by convention.

apps/webapp/app/services/dashboardAgentWatchChecks.ts (1)

102-122: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use the shared FINAL_RUN_STATUSES set for run terminality.

FINAL_STATUSES duplicates apps/webapp/app/v3/taskStatus.FINAL_RUN_STATUSES and can silently drift if a terminal status changes. Since this file only imports isomorphic utilities for ErrorId and durations, avoid importing the mostly server-side ~/v3/taskStatus module here; instead split the shared status constants/constants into an isomorphic helper and import it from this module.

apps/webapp/app/routes/api.v1.queues.$queueParam.metrics.ts (1)

23-24: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Narrow UNIT_MS so period multiplications stay type-exact.

UNIT_MS is annotated as Record<string, number>, and these app configs enable strict mode but not noUncheckedIndexedAccess, so the * in UNIT_MS[p.slice(-1)] and UNIT_MS.d is typed as number regardless of the actual key set. Use a keyed PeriodUnit value and narrow the index so the compiler rejects invalid suffixes before they can affect the refiner or periodMs().

Also applies to: 42-44

apps/webapp/app/routes/storybook.agent-ui/route.tsx (1)

437-459: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Orphaned doc comment: the URI-resolver doc is attached to investigationBlock.

The block at Lines 437-441 documents fixtureResolveUri, but that function is defined at Line 518; here it sits immediately above a second JSDoc for investigationBlock, leaving two stacked comments and the resolver undocumented at its definition.

♻️ Move the resolver doc to its definition

-/**
- * The gallery's stand-in for the panel's URI resolver. In the app the host
- * resolves against the real environment (`resolveTriggerUri.server.ts`); here a
- * fixture resolver proves the seam exists without a project route.
- */
 /**
  * The demo investigation fixtures, as the real `investigation` block: the demo

And at Line 518:

+/**
+ * The gallery's stand-in for the panel's URI resolver. In the app the host
+ * resolves against the real environment (`resolveTriggerUri.server.ts`); here a
+ * fixture resolver proves the seam exists without a project route.
+ */
 function fixtureResolveUri(uri: string): { label: string; url: string } | null {

apps/webapp/scripts/agent-ui-screenshots.ts (1)

220-243: 🩺 Stability & Availability | 🔵 Trivial | 💤 Low value

Panel presence check may short-circuit when the panel is in the DOM but hidden.

openPanel returns early on count() > 0, so if the panel element persists while closed (e.g. mounted but translated/hidden), the launcher is never clicked and the subsequent capture(panel) screenshots a collapsed element. Gating on visibility instead is more robust for the chat walk.

🛠️ Gate on visibility

-  const panel = page.locator(PANEL_SELECTOR);
-  if (!(await panel.count())) {
+  const panel = page.locator(PANEL_SELECTOR);
+  if (!(await panel.isVisible().catch(() => false))) {

apps/webapp/app/components/dashboard-agent/demo/fixtures/intents.ts (1)

71-74: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Avoid duplicating the investigation id as a string literal.

investigationId: "demo:investigation-order-receipt" duplicates what fixtures/investigation.ts already computes as demoId("investigation-order-receipt") for demoInvestigationConcluded. Importing that value avoids silent drift if the investigation fixture's id is ever renamed.

♻️ Suggested fix

-import { isExecutableIntent, type AgentIntent } from "`@internal/dashboard-agent-contracts`";
+import { isExecutableIntent, type AgentIntent } from "`@internal/dashboard-agent-contracts`";
+import { demoInvestigationConcluded } from "./investigation";
 import { DEMO_WORLD, demoRunUri } from "../ids";
 ...
 export const demoProposeFixIntent = demoIntent(
-  { kind: "propose_fix", investigationId: "demo:investigation-order-receipt" },
+  { kind: "propose_fix", investigationId: demoInvestigationConcluded.investigationId },
   "Rejected: proposing a fix isn't available yet"
 );

apps/webapp/app/components/dashboard-agent/RunDiagnosisCard.tsx (1)

79-81: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Raw indigo palette classes bypass the theme-remapping layer. Both new styles hardcode Tailwind palette classes, while agent-badges.tsx (lines 30-31) and report-sparkline.tsx (lines 39-40) added in this same PR explicitly state that palette classes are tuned for the dark theme only and that semantic tokens are what the theme layer remaps.

• apps/webapp/app/components/dashboard-agent/RunDiagnosisCard.tsx#L79-L81: replace LINK_STYLE's text-indigo-500 hover:text-indigo-400 with the text-text-link token already used by InvestigationCard.tsx (line 89) and ReportFooterLink.
• apps/webapp/app/components/primitives/Callout.tsx#L63-L70: give the agent variant a semantic token (e.g. a callout-agent token alongside the existing callout-docs/callout-pricing tokens) instead of border-indigo-500/20, bg-indigo-500/10 and text-indigo-500.

apps/webapp/app/components/primitives/Callout.tsx (1)

63-70: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Raw indigo palette classes won't be remapped by the theme layer.

Every other variant in this map uses semantic tokens (callout-docs, success, warning, error); the agent frame and icon hardcode indigo-500. See the consolidated note with RunDiagnosisCard.tsx for the shared fix.

apps/webapp/app/components/dashboard-agent/DashboardAgentMessages.tsx (1)

117-140: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Raw "output-error" string literal comparison.

p.state === "output-error" is compared as a raw literal here; the same literal is duplicated in report-block-adapter.ts and AgentMessageView.tsx. See consolidated comment for a shared-constant suggestion.

Source: Coding guidelines

apps/webapp/app/components/dashboard-agent/chat-layout.tsx (1)

236-284: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

ChatToolRow/ChatStatusLine don't self-apply the transcript inset when mounted loose.

Per rule 2 in this file's own docstring, a micro-layout mounted outside a ChatTurn must apply the inset itself (ChatProgress, ChatPendingTool, ChatNote all do this via useInsetClass()). ChatToolRow and ChatStatusLine don't call useInsetClass(), so if either is ever mounted loose (e.g. a tool row under a card), it will render without the horizontal inset, breaking alignment with the rest of the transcript. Neither is exercised in this diff yet, so confirm whether they're intentionally turn-only.

apps/webapp/app/components/dashboard-agent/report-block-adapter.ts (1)

50-56: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Raw "output-available" string literal comparison.

Same sentinel-value pattern as in DashboardAgentMessages.tsx and AgentMessageView.tsx — see consolidated comment.

Source: Coding guidelines

apps/webapp/app/components/runs/v3/agent/AgentMessageView.tsx (2)

164-188: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Raw tool-part state string literals.

This function is the biggest concentration of raw AI-SDK tool-part state comparisons ("output-error", "input-streaming", "input-available", "approval-requested", "approval-responded", "output-denied") in the reviewed diff. See consolidated comment for a shared-constant suggestion.

Source: Coding guidelines

---

1-1: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Extract shared named constants for AI-SDK tool-part state strings.

AgentMessageView.tsx, DashboardAgentMessages.tsx, and report-block-adapter.ts each independently compare p.state against raw literals ("output-error", "output-available", "input-streaming", "input-available", "approval-requested", "approval-responded", "output-denied"). progress-line.ts's IN_FLIGHT_TOOL_STATES already shows the right pattern for two of these; extending it (or a sibling constants module) to cover the rest would remove the duplication and the risk of a typo silently breaking one of these comparisons in a state machine that several files rely on independently.

• apps/webapp/app/components/runs/v3/agent/AgentMessageView.tsx#L164-188: replace the raw "output-error", "input-streaming", "input-available", "approval-requested", "approval-responded", "output-denied" literals with shared named constants.
• apps/webapp/app/components/dashboard-agent/DashboardAgentMessages.tsx#L117-140: replace the raw "output-error" literal in renderDashboardPart with the same shared constant.
• apps/webapp/app/components/dashboard-agent/report-block-adapter.ts#L50-56: replace the raw "output-available" literal with the same shared constant.

Source: Coding guidelines

apps/webapp/app/presenters/v3/waitingRun/waitingRunDiagnosis.server.ts (1)

153-161: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value

Carry-forward seed of 0 can understate early buckets.

Buckets before the first emission are filled with 0 rather than left unknown, so a queue whose first metric row lands mid-window renders a fake "empty then spike" shape in the sparkline. sampleBuckets protects the ETA, but the series itself is user-visible. Consider starting from the first observed bucket (e.g. skip leading positions until byIndex has a value, or backfill with the first known depth).

apps/webapp/app/components/dashboard-agent/suggested-prompts/registry.ts (1)

217-222: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

SIGNAL_PRIORITY is not exhaustiveness-checked, unlike SIGNAL_SLOT.

Both contextualPrompts and contextualPromptsBySlot iterate SIGNAL_PRIORITY, so a signal kind added to the contract but omitted here produces no chip at all — silently, since AgentPageSignalKind[] accepts a partial list. SIGNAL_SLOT (a Record) would fail to compile in the same situation; make the priority list fail the same way.

♻️ Force a compile error on a missing kind

-export const SIGNAL_PRIORITY: AgentPageSignalKind[] = [
+export const SIGNAL_PRIORITY = [
   "fresh_failure",
   "waiting_run",
   "slow_run",
   "concurrency_saturation",
-];
+] as const satisfies readonly AgentPageSignalKind[] &
+  Record<0 | 1 | 2 | 3, AgentPageSignalKind>;

Simpler alternative: derive it from the SIGNAL_SLOT keys and sort, or add a type-level assertion that the union of SIGNAL_PRIORITY[number] equals AgentPageSignalKind.

apps/webapp/app/components/dashboard-agent/suggested-prompts/resolver.test.ts (1)

164-172: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

This assertion becomes a tautology if the fixture's page kind changes.

toContain("") always passes, so the branch is silently self-disabling — exactly the case the throw new Error("fixture changed") guards elsewhere in this file (lines 223, 228) exist to prevent. Narrow first instead.

💚 Proposed fix

-    const [failure] = resolveSuggestedPrompts(demoPageContexts.failedRun, { now: NOW });
-
-    expect(failure?.label).toBe("Why did this run fail?");
-    expect(failure?.prompt).toContain(
-      demoPageContexts.failedRun.page.kind === "run" ? demoPageContexts.failedRun.page.runId : ""
-    );
-    expect(failure?.prompt).toContain("12m ago");
+    const page = demoPageContexts.failedRun.page;
+    if (page.kind !== "run") throw new Error("fixture changed");
+    const [failure] = resolveSuggestedPrompts(demoPageContexts.failedRun, { now: NOW });
+
+    expect(failure?.label).toBe("Why did this run fail?");
+    expect(failure?.prompt).toContain(page.runId);
+    expect(failure?.prompt).toContain("12m ago");

apps/webapp/app/components/dashboard-agent/suggested-prompts/resolver.ts (1)

67-67: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Truncation drops the docs chip, contradicting the "always last, always present" invariant.

slice(0, CAP) cuts from the tail, and docs is the last slot. Today the cap presumably equals the slot count, so nothing is dropped — but if SUGGESTED_PROMPT_CAP is ever lowered, the documented guarantee (this file's header, and registry.ts line 14) silently breaks in favour of a lower-priority chip. Reserving the docs slot before the cap, or asserting CAP >= PROMPT_SLOTS.length + 1 at module load, keeps the invariant honest.

apps/webapp/app/components/dashboard-agent/DashboardAgentMessages.tsx (1)

351-368: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Memoize the transcript-derived winner map.

Line 357 creates a new Map on every render, and Line 368 passes it to memoized turns; activity-only updates therefore rerender the entire transcript and rescan all parts. Memoize stripped and its winners from messages.

Proposed change

-  const stripped = messages.map(stripStepParts);
-
-  const investigationWinners = winningInvestigationOccurrences(stripped);
+  const { stripped, investigationWinners } = useMemo(() => {
+    const stripped = messages.map(stripStepParts);
+    return {
+      stripped,
+      investigationWinners: winningInvestigationOccurrences(stripped),
+    };
+  }, [messages]);

As per coding guidelines, useMemo is appropriate for expensive derived data and stable references required by dependency arrays.

Source: Coding guidelines